Crate onetaskgraph_plugin_api

Expand description

The contract every onetaskgraph source is written against.

This crate holds exactly what a plugin author needs in order to implement a source, and nothing else: the two traits, the work types, the query and paging types, the capability declaration, and the error enum. The engine that drives sources lives in onetaskgraph-core, and no plugin crate may depend on it: deny.toml permits that crate exactly one wrapper, the binary, failing the required deny job, and scripts/check-plugin-isolation.sh reads the real cargo metadata graph inside just check.

Keeping this crate still is the point. Every change here rebuilds and re-tests every plugin, which is exactly the cost the split exists to avoid paying on an ordinary engine change. When a new type could plausibly sit on either side, it belongs in onetaskgraph-core unless a trait signature names it.

Structs§

Asset: One asset a record holds, as a read reports it.
AssetName: One asset’s name: a bare file name ending in an accepted image extension.
AssetPayload: One asset a create or an update carries to a destination.
AssetUpload: What a hosted source uploaded for one asset of one record: the bytes’ SHA-256 and the URL it serves them at.
AssetUploads: The value of MetadataKey::ASSETS_KEY on a destination record: what its hosted source uploaded, by asset name.
AssetWrite: The assets a create or an update of one task or document carries.
AssetsWritten: What an asset-carrying write answers with: where the record now is, and the content the destination stored.
Capabilities: One source’s declared abilities.
Comment: One comment on a task, as its source holds it.
CommentBody: What a comment says: anything at all, except nothing.
Cursor: A plugin-defined resume token. The engine stores and returns one; it never interprets one.
DependencyEdge: A dependency between two work items.
DependencyEndpoint: One endpoint of a dependency edge.
Document: One piece of information that lives in a project and is not work.
DocumentQuery: A filter over a source’s documents.
Health: Whether a source is answering right now.
ItemWrite: One create-or-update of a work item at a destination.
Label: A tag a source attaches to work.
LabelFilter: Label membership, by name rather than by id.
MetadataKey: One caller-owned metadata key: <namespace>.<name>, at least two non-empty segments separated by dots, whose first segment is not MetadataKey::RESERVED_NAMESPACE.
MetadataMatch: One caller-defined metadata value a task must hold.
Metered: What one source’s requests have spent against one budget, split by where each figure came from.
Metering: Everything one source has sent to its backend since it was built, and what that spent against each budget the backend meters it by.
NativeId: A source’s own opaque identifier for one item.
NewComment: One comment to add to a task.
Page: One page of results, and where to pick up.
PageRequest: One step of a walk through a result set.
Project: A grouping of tasks, shaped like a Task without a parent of its own.
ProjectQuery: A filter over a source’s projects.
Repository: A repository identified by its normalized origin, without a URL scheme or .git suffix.
SourceName: The name a configuration document gives one configured source.
Status: A source’s status, kept in both normalised and original form.
StatusMapping: One source’s status_mapping: for each status category it mentions, the names it gives each item kind, or null.
StatusName: One status name a source’s backend holds: a board option, a workflow state, a project status.
Task: One unit of work as a source reports it.
TaskDetailRead: One task as TaskSource::get_task_details reads it: the task, and the first page of its comments when they were asked for.
TaskQuery: A filter over a source’s tasks.
TaskRef: One task named by another task’s Task::delivers or Task::delivered_by.
TaskUpdate: A targeted update of one existing task. A member left None (or empty) leaves that field exactly as the source holds it.
TaskUpdateOutcome: What a source answers a TaskUpdate of a task it holds with.
TextQuery: A free-text search and the fields it searches.

Enums§

AssetContentType: The content type an asset is stored and served as, decided by its name’s extension alone.
DependencyKind: What a DependencyEdge means.
DependencySupport: How far a source can walk its own dependency edges.
Direction: Which way a dependency query walks the graph.
ItemKind: The kind of work item named by a dependency endpoint.
Location: Where an entity is, in the one form a consumer can act on without knowing the backend.
MetadataRecord: Which kind of record a narrow metadata write names.
Priority: How much a task matters, in the one vocabulary every source is normalised into.
ProjectFilter: Which project a task must belong to.
SourceError: Why a source could not answer.
StatusCategory: The normalised status vocabulary shared across every source.
StatusNames: What one category of a status_mapping names: one name for every kind, or a name for each kind it maps.
Support: Whether a source applies one predicate itself.
TextFields: Which fields a TextQuery searches.
UnmappedStatus: Why a mapping gives no name for one category and one kind.
UpdatedField: One field of a task a TaskUpdate names, as the answer to it reports what was written.
WriteSupport: Whether a source can be written through at all.

Constants§

SIMULATED_CLOCK_VARIABLE: The variable that puts a process of this build on a simulated clock.
SOURCE_NAME_PATTERN: The pattern every SourceName matches.

Traits§

Clock: A source of monotonic time and of waits measured against it.
SecretResolver: How a plugin reads the credential its configuration names.
SourcePlugin: The factory that turns one configuration block into a live TaskSource.
TaskSource: One configured source, as the engine drives it.

Functions§

asset_references: The assets content references, each once, in the order it first references them.
asset_sha256: The lowercase hex SHA-256 of bytes: what Asset::sha256, AssetPayload::sha256 and AssetUpload::sha256 hold.
assetless: The refusal a source that keeps no assets answers an asset write with.
body_digest: sha256: and the lowercase hex SHA-256 of content: what a rendering’s body_digest records.
commentless: The refusal a source with no comments answers a comment call with.
documentless: The refusal a source with no documents answers a document read with.
is_sha256: Whether digest is a SHA-256 as this contract spells one: 64 lowercase hex digits.
rewrite_asset_references: content with the target of each reference to an asset served names replaced by the URL it maps to, and every other byte as it was.
serve_asset_references: Point a record’s asset references at where a hosted source serves them, and record what it uploaded: the one way a plugin that declares assets native and serves them at a URL finishes the record it is about to write.
system_clock: The real clock: tokio::time::sleep and a monotonic Instant.
unwritable: The refusal a source with no write side answers a write with.
unwritable_field: The refusal a source answers a narrow write of one field of a task with, when it cannot write that field on its own.
unwritable_metadata: The refusal a source answers a narrow metadata write with when it cannot make one on its own.

Type Aliases§

SharedClock: One clock, shared by everything a process builds.